home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / winsock / wlprs40c.zip / WLPR2.ASC < prev    next >
Text File  |  1994-12-21  |  16KB  |  374 lines
  1. WLPR2.DLL Version 2.0c - UserÆs Guide
  2.                       WLPR2.DLL Version 2.0c - UserÆs Guide
  3. 10
  4.                                                           2
  5.                              
  6.                              
  7.                              
  8.                              
  9.                              
  10.                              
  11.                              
  12.                              
  13.                              
  14.                              
  15.                              
  16.                              
  17.                          WLPR2.DLL
  18.                        Version 2.0c
  19.                              
  20.                              
  21.                        User's Guide
  22.                              
  23.                              
  24.                      December 21, 1994
  25.                              
  26.                              
  27.                              
  28.                              
  29.                              
  30.                              
  31.                              
  32.                         Thomas Heil
  33. This  document was created with Microsoft Word for  Windows
  34. 6.0
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41. DISCLAIMER:
  42.  
  43. THE  SOFTWARE  IS PROVIDED AS-IS. THE AUTHOR DISCLAIMS  ALL
  44. WARRANTIES,  EITHER EXPRESS OR IMPLIED, INCLUDING  BUT  NOT
  45. LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
  46. FOR  A  PARTICULAR  PURPOSE. NO LIABILITY  IS  ASSUMED  FOR
  47. DAMAGES, DIRECT OR CONSEQUENTIAL, WHICH MAY RESULT FROM THE
  48. USE OF THIS SOFTWARE.
  49.  
  50. (C) Copyright 1992-94 by Thomas Heil.
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61. All  trademarks appearing in this document are the property
  62. of their respective owners.
  63.  
  64.  
  65. Table of Contents
  66.  
  67. Table of Contents                                         3
  68. Introduction                                              5
  69. Copyright:                                                5
  70. Author:                                                   5
  71. New Features in Version 2.0                               6
  72. Setting Properties for Remote Queues                      6
  73. DLL Settings                                              9
  74.     Section Miscellaneous:                                 9
  75.     Section Timeouts:                                      9
  76. Known problems:                                           9
  77. Troubleshooting:                                         10
  78. Change Log:                                              10
  79.  
  80.  
  81. _Introduction
  82.  
  83. WLPR2.DLL  contains  a  set of API  functions  that  allow  an
  84. application  to print to remote printers, query their  queues,
  85. and  remove print jobs from their queues. These printers  must
  86. understand the LPR/LPD protocol which is defined in RFC  1179.
  87. An  application  that calls this DLL does not need to have any
  88. knowledge  about  the  implementation  details.  It  may  call
  89. functions  in this DLL to set/modify properties for individual
  90. queues,  such as number of copies to print, whether  a  banner
  91. page shall be generated, etc.
  92.  
  93.  
  94. Copyright:
  95.  
  96. This   DLL   is   Copyright  (C)  1993-94  by   Thomas   Heil.
  97. Redistribution of this DLL is allowed only together  with  the
  98. documentation (as PostScript .PS file and as plain ASCII  .ASC
  99. file).  This  software may not be sold by itself. Applications
  100. that  use this DLL may be sold together with the DLL  and  its
  101. documentation included royalty free.
  102.  
  103. If  you want to write a similar DLL that implements the  WLPR2
  104. API  for another protocol, please feel free to contact me  for
  105. implementation details.
  106.  
  107.  
  108. Author:
  109.  
  110. Thomas Heil
  111. Hindenburgstr. 50
  112. 41352 Korschenbroich
  113. E-Mail: th.heil@kfa-juelich.de (Internet)
  114. CompuServe: 100434,2167
  115.  
  116. Phone: +49 2161 644895
  117. Fax: +49 2161 644337
  118.  
  119.  
  120. New Features in Version 2.0
  121.  
  122. The  DLL  was totally restructured. Now all protocol  relevant
  123. stuff is totally included in the DLL. E.g. with version 1.x an
  124. application  had to have an own dialog for setting  the  queue
  125. properties.  Now that is all handled by the DLL  itself  which
  126. exports  an  appropriate  function.  This  makes  the  calling
  127. application independant of the implementation specifics of the
  128. transport  protocol,  and allows it to use  several  different
  129. Protocol DLLs that offer the WLPR2 API side by side.
  130.  
  131. This DLL is not compatible with WLPR.DLL Version 1.x.
  132.  
  133.  
  134. Setting Properties for Remote Queues
  135.  
  136. If  your  application allows you to view/change the properties
  137. of a remote queue, you get a dialog that looks like this:
  138.  
  139.  
  140.  
  141. In this dialog, the following settings can be made:
  142.  
  143. Send header     If  checked,  a header page is generated  with
  144. page:           each  print  job.  If not checked,  no  header
  145.                 page  is  printed.  Note that  this  might  be
  146.                 overridden  by  the  settings  of  the  remote
  147.                 print server (default: on).
  148. Copies:         Set  the  number of copies that  a  print  job
  149.                 generates (default: 1).
  150. CRLF->LF        Normally,  files  going to  a  queue  of  type
  151. conversion      "Formatted  File  (f)" and  "Print  with  'pr'
  152.                 (p)"  run  through  a filter  that  translates
  153.                 CRLF  sequences to single LineFeeds. This  can
  154.                 be  switched off with this check box (default:
  155.                 Filtering is on).
  156. Omit domain     If  you have long Internet names for your PC's
  157. from PC's       which  are  too  long for your  server  to  be
  158. hostname:       accepted  (as  can happen with some  Macintosh
  159.                 based  LPD implementations) you can  have  the
  160.                 PC's  hostname  truncated  to  just  the  non-
  161.                 domain part.
  162. Class:          Sets  the job class of print jobs that  go  to
  163.                 this  queue to a fixed value. This class  name
  164.                 might  be  interpreted by the print server  in
  165.                 some  way. Check with your local print  server
  166.                 administration  for  classes  that  have  some
  167.                 relevance.  (Default:  The  PC's  hostname  is
  168.                 passed as class to the server).
  169. Title:          Sets the document title of print jobs that  go
  170.                 to  this queue to a fixed value. (Default: The
  171.                 title that the printing application passes  to
  172.                 the DLL is taken).
  173. Jobname:        Sets  the  jobname of print jobs  that  go  to
  174.                 this  queue  to  a fixed value.  This  jobname
  175.                 might  be  interpreted by the print server  in
  176.                 some  way. Check with your local print  server
  177.                 administration  for jobnames  that  have  some
  178.                 relevance.  If  the  next  option  is  checked
  179.                 though,  the  job  title is  used  as  jobname
  180.                 (Default:  The name of the file being  printed
  181.                 is taken as the jobname).
  182. Set jobname     If  checked,  the jobname is set to  what  the
  183. same as title:  job title is.
  184. Replace spaces  All  space  characters in the  job  title  are
  185. with _ in       replaced  with underscore characters in  order
  186. title:          to make it one token.
  187. File Type:      The  given file types are those that RFC  1179
  188.                 defines,  although  normally  just   a   small
  189.                 subset  is really needed. The problem is  that
  190.                 not  every  server accepts all types,  so  you
  191.                 might  have  to try a bit around.  You  should
  192.                 take  the  following approach:  If  PostScript
  193.                 files  or plain ASCII files are sent  to  this
  194.                 queue, you should select "Formatted File".  If
  195.                 you  send  binary  printer data  (e.g.  output
  196.                 from  a Windows printer driver) to this queue,
  197.                 you  should select "Raw Print File". Note that
  198.                 the type "Postscript File" is not accepted  by
  199.                 a lot of LPD implementations.
  200.                 Plain  ASCII files can also be sent  with  the
  201.                 setting   "Print  with  'pr'".  This  normally
  202.                 means  that  the  file is  sent  through  some
  203.                 formatting  filter on the print  server  which
  204.                 allows  header  lines to  be  written  on  the
  205.                 output.  If  you  select  this  type  you  can
  206.                 specify  the  desired  page  header  line   as
  207.                 "Document  Title", and also modify margin  and
  208.                 line width settings.
  209.                 If  you  select TROFF/DITROFF output  you  can
  210.                 specify which fonts shall be used for output.
  211.                 The  file  types "Formatted File"  and  "Print
  212.                 with  'pr'"  cause  the  print  file  to   run
  213.                 through     a     filter     that     converts
  214.                 CarriageReturn/LineFeed sequences to a  single
  215.                 LineFeed.
  216. Long query      If  checked,  the  user gets  a  more  verbose
  217.                 listing   when  querying  the  remote   queue.
  218.                 Otherwise he gets a standard listing.
  219.  
  220. There are additional options available when you select one  of
  221. the  document types 'p', 'n', or 't'. In this case the  button
  222. "Type  specific options..." is enabled. If you click  on  this
  223. button,  you get another dialog. For the type 'p' you may  set
  224. the  indention and document width in terms of characters.  For
  225. the types 'n' and 't' you may set different font names for the
  226. nroff/troff document to be printed.
  227.  
  228. The  user may specify a specific file to be prepended  to  the
  229. print data as well as one that is appended by clicking on  the
  230. ôInclude  files...ö button and selecting appropriate files  in
  231. the  next  dialog. This allows initialization  data  or  reset
  232. sequences  to  be passed to the printer before  or  after  the
  233. actual print job. Note that even for queues of type æfÆ or æpÆ
  234. for which filtering is enabled, the contents of the prepend or
  235. append files are never filtered.
  236.  
  237. When the dialog contains just an "Ok" button, the settings are
  238. saved when this button is pressed. When the dialog contains an
  239. additional  "OK / Save" button and the user just  presses  the
  240. "Ok"  button, the settings apply only to the action  that  the
  241. calling  application is about to perform,  but  they  are  not
  242. permanently changed. If, in this case, you want to  make  your
  243. changes permanent, press the "Ok / Save"  button.
  244.  
  245. The  last  button "DLL Setup..." allows the user to  influence
  246. how  the DLL operates in general. These settings are described
  247. below in the section "DLL Settings".
  248.  
  249.  
  250. DLL Settings
  251.  
  252. The following settings that influence the behaviour of the DLL
  253. can  be  made in the "DLL Setup..." dialog. Don't change  them
  254. unless  you  think there is a reason to do so (e.g. connection
  255. problems).
  256. Section Miscellaneous:
  257.  
  258. Debug mode     If checked, the DLL operates in debug mode. See
  259.                the section "Troubleshooting" below for details
  260.                on this mode. Default is true.
  261. Reset connection after LPQ    If checked, the socket
  262.                connection is reset after an LPQ or LPRM
  263.                request. This was necessary for some older
  264.                versions of a few TCP/IP stacks in order to
  265.                reuse  TCP port numbers. Default is true.
  266. Linger time    If 0, the "linger" socket option for
  267.                connections is explicitly set to SO_DONTLINGER.
  268.                If >0, the "linger" option is set to SO_LINGER
  269.                (enabled), and the number specified determines
  270.                the timeout in seconds.
  271.                If -1, the socket's linger setting remains the
  272.                same as it was when WINSOCK.DLL created the
  273.                socket.
  274.                Default is -1 (linger setting remains
  275.                unchanged). If you have problems with
  276.                connections that sometimes work and sometimes
  277.                not (or fail every other time) set this value
  278.                to something different than -1.
  279. Section Timeouts:
  280.  
  281. Connect timeoutTime (in seconds) after which a not yet
  282.                established connection to a server fails.
  283.                Default is 30.
  284. Send/receive timeout   Time (in seconds) after which a send or
  285.                receive operation to/from a server fails if
  286.                there is no progress.
  287. Close timeout  Time (in seconds) allowed for a server to react
  288.                on a connection closed by the DLL (by closing
  289.                the connection, too) before the connection is
  290.                reset.
  291.  
  292.  
  293.  
  294. Known problems:
  295.  
  296.    Some WINSOCK implementations create problems when a program
  297.    tries  to  close  a  non-blocking  socket  gracefully.  The
  298.    problem  can  be  circumvented by setting  the  TCP  linger
  299.    option  for  the  socket connection to a  non-zero  timeout
  300.    value in the "DLL Setup..." dialog.
  301.    If  queries  for  a remote queue status hang  after  a  few
  302.    attempts  (or  every  other try) make sure  that  the  item
  303.    "Reset  connection after LPQ" in the "DLL Setup..."  dialog
  304.    is checked.
  305.  
  306.  
  307. Troubleshooting:
  308.  
  309. If you have problems with an application that prints by use of
  310. this  DLL, please don't hesitate to contact me. But please  do
  311. one  thing  before  that so that I get some information  about
  312. what  is  happening: Switch the DLL into  debug  mode  in  the
  313. "DLL Setup..." dialog. After this WLPR2.DLL writes a debug log
  314. to  the  file C:\WLPRDEB.LST. (Note that you have to stop  all
  315. programs  using  WLPR2.DLL   and  restart  them  to  get  this
  316. effective  because  this INI entry is  checked   at  DLL  load
  317. time).   This  file  is  overwritten  with  each  LPR/LPQ/LPRM
  318. request.  When you did one of those requests and  you  got  an
  319. error,  immediately rename the above file to some  other  name
  320. before  you  execute another request. Then mail me this  file.
  321. When  all  problems  are resolved you can disable  debug  mode
  322. again.
  323.  
  324.  
  325. Change Log:
  326.  
  327. Version 2.0a:
  328.  
  329.    WSACleanup()  was  not  called  when  the  WINSOCK.DLL  was
  330.    unloaded.
  331.    Default  for the "Reset after LPQ" DLL setting  changed  to
  332.    "yes".
  333.    Now  the user may explicitly define whether files in queues
  334.    of  type  "Formatted file (f)" and "Print  with  'pr'  (p)"
  335.    shall run through a CRLF->LF filter.
  336.    If  the networking software (or WSOCKAID.DLL, respectively)
  337.    cannot   return  a  username  to  WLPR2.DLL  (because   the
  338.    networking software does not have something like  this  and
  339.    the  user  did  not  set one with the WSAIDCNF.CPL  Control
  340.    Panel  applet coming with WSOCKAID.DLL), a default username
  341.    "pcuser" is used by WLPR2.DLL. The user is notified of this
  342.    fact  with a message box the first time he tries to  print.
  343.    Later prints use this default without further notification.
  344.    Removed  a bug which caused an LPQ request to hang on  some
  345.    WINSOCK implementations.
  346.    All  timeout parameters for a connection can now  be  user-
  347.    defined in the "DLL Setup..." dialog.
  348.  
  349. Version 2.0b:
  350.  
  351.    When trying to remove a print job and WSOCKAID.DLL did  not
  352.    return a valid username, the default username "pcuser"  was
  353.    not used.
  354.    Now the user can specify class name, job name and job title
  355.    as fixed values for a queue.
  356.    New  options "Omit domain from PC's hostname", "Set jobname
  357.    same as title", and "Replace spaces with _ in title".
  358.    Moved document type specific options to sub-dialog.
  359.    Now the query results from Lantronix print server boxes are
  360.    shown correctly.
  361.    The  user  now can specify a file to be prepended  to  each
  362.    print  job  as well as one to be appended. This  allows  to
  363.    pass  personal banner pages or printer initialization  data
  364.    to the printer before or after the actual print data.
  365.    If  a  PC does not have a hostname assigned, the IP address
  366.    of the PC will be used. The user is notified of this once.
  367. Version 2.0c:
  368.  
  369.    The  send/receive timeout can be set to 0 wich  effectively
  370.    disables any timeout.
  371.    The TCP port for a queue can now be configured. Default  is
  372.    port 515
  373.  
  374.